<html>
<head>
<title>The NewOS Operating System: Docs</title>
</head>
<body BGCOLOR="#FFFFFF">

<h1 align="center">NewOS shell manual<br>Version 0.2-pre 1</h1>

<hr>

<hr>

<table border="0" width="100%" bgcolor="#E8E8E8">
 <tr>
  <td width="100%" height="100%" valign="top" align="left">
   <center><h3>Contents</h3></center>
   <ol>
    <li><a href="#What_is_missing">What is missing</a></li>
    <li><a href="#Running_a_shell_script">The shell</a></li>
    <ol>
     <li><a href="#Running_a_shell_script">Running a shell script</a>
    </ol>
    <li><a href="#Introduction">Introduction</a></li>
    <li><a href="#Variables">Variables</a></li>
    <ol>
     <li><a href="#Variable_Syntax">Syntax</a></li>
     <li><a href="#Strings">Numbers and Strings</a></li>
     <li><a href="#Build_in_variables">Build in variables</a></li>
    </ol>
    <li><a href="#Operators">Operators</a></li>
    <li><a href="#Functions">Functions</a></li>
    <ol>
     <li><a href="#exec_function">exec</a></li>
     <li><a href="#casting">type casting</a></li>
    </ol>
    <li><a href="#Statements">Statements</a></li>
    <ol>
     <li><a href="#Comments">Comments</a></li>
     <li><a href="#exec">exec</a></li>
     <li><a href="#exit">exit</a></li>
     <li><a href="#goto">goto</a></li>
     <li><a href="#if">if</a></li>
     <li><a href="#labels">label</a></li>
    </ol>
   </ol>
  </td>
 </tr>
</table>

<hr>

<table border="0" width="100%" bgcolor="#E8E8E8">
 <tr>
  <td width="100%" height="100%" valign="top" align="left">
   <a name="What_is_missing"></a>
   <center><h3>What is missing</h3></center>
   The following features are missing but are added in the next release:<br>
   <ul>
    <li>And,or,xor</li>
    <li>Output redirection of 'echo' statement</li>
    <li>else?</li>
    <li>not operator?</li>
    <li>More...</li>
   </ul>
  </td>
 </tr>
</table>

<hr>

<table border="0" width="100%" bgcolor="#E8E8E8">
 <tr>
  <td width="100%" height="100%" valign="top" align="left">
   <a name="The_shell"></a>
   <center><h3>The shell</h3></center>
   <b>Command line options</b><br><br>
   &nbsp;&nbsp;&nbsp;shell [-s] [&lt;script_name&gt; &lt;arguments&gt;]<br><br>
   When the &lt;script_name&gt; is given as parameters the shell starts
   the interpretor and  runs the script otherwise the shell starts an 
   interactive session.All options before &nbsp;the script name are handled 
   as shell parameters. An option is everything which   starts with a '-'.<br>
   The script name is placed in the variable $p0 and the flowing &lt;arguments&gt;
   are &nbsp;placed in $p1..$p??. $argc contains the number of arguments. The
   path in $path is used as search path for the script. The $path value is&nbsp;
   hard coded in the shell.<br>
   By default the shell exits after when&nbsp; the script ends, but with
   the '-s' option   the shell starts an interactive session.<br>
  </td>
 </tr>
</table>

<hr>

<table border="0" width="100%" bgcolor="#E8E8E8">
 <tr>
  <td width="100%" height="100%" valign="top" align="left">
   <a name="Introduction"></a>
   <center><h3>Script language Introduction</h3></center>
   The shell script language has the following features:<br>
   <ul>
    <li>Case sensitive</li>
    <li>Identifier names:<br>
      Starts with a alphabetic symbol and a number,alphabetic or a '_'  symbols
      can follow.<br>
      Variables :$&lt;identifier_name&gt;<br>
      Label : &lt;identifier_name&gt;:
    </li>
    <li>if, goto</li>
    <li>Formula's</li>
    <li>etc...</li>
   </ul>
  </td>
 </tr>
</table>

<hr>

<table border="0" width="100%" bgcolor="#E8E8E8">
 <tr>
  <td width="100%" height="100%" valign="top" align="left">
   <a name="Variables"></a>
   <center><h3>Variables</h3></center>
   <a name="Variable_Syntax"></a>
   <b>Syntax</b><br>
   The syntax of a variable name is $&lt;Identifier&gt;.<br> 
   $a=&lt;value&gt; , defines a variable. <br>
   A variable can't be removed yet.<br>
   When a new script is started the variables are not shared with the new process.
   <br><br>
   <a name="Strings"></a>
   <b>Numbers and Strings</b><br>
   Numbers are stored and handled as&nbsp; 64 bit signed integers<br>
   <br>
   Strings can start and end with single or double quotes. In double quoted strings 
   variables (starting with a $) are substituted by their value.<br>
   The shell variables doesn't have a type, it can contain a string or a number.<br>
   It is not possible to mix strings and numbers in formula's. More info:
   <a href="#Operators">Operators</a>
   When a value is a string or a number, depends on how they are defined and not
   on their contents:<br>
   <br>
   $a='1', &nbsp; $a contains a string.<br>
   <br>
   $b= 1 , &nbsp; $b contains a number<br>
   <br>
   $c=$a+$b this fails because $a contains a string and $b contains a number.<br>
   <br>
   <a name="Build_in_variables"></a>
   <b>Built in variables</b><br>
   <table cellpadding="2" cellspacing="2" border="1" width="100%">
    <tr>
     <td valign="Top">$path</td>
     <td valign="Top">Search path for programs</td>
    </tr>
    <tr>
     <td valign="Top">$argc</td>
     <td valign="Top">number of arguments</td>
    </tr>
    <tr>
     <td valign="Top">$p0</td>
     <td valign="Top">Parameter 0, which is the script filename</td>
    </tr>
    <tr>
     <td valign="Top">$p1...p&lt;no&gt;</td>
     <td valign="Top">Script parameters</td>
    </tr>
   </table>
   <b>Note:</b><br>
   Parameters are stored as strings. When parameters are used with numbers 
   they must be cast:<br>
   <br>
   <b>if(number($p1) == 1) goto the_end</b><br>
   or<br>
   <b>if($p1 == "1") goto the_end</b><br>
   following will fail:<br>
   <b>if($p1 == 1) goto the_end</b><br>
  </td>
 </tr>
</table>

<hr>

<table border="0" width="100%" bgcolor="#E8E8E8">
 <tr>
  <td width="100%" height="100%" valign="top" align="left">
   <a name="Operators"></a>
   <center><h3>Operators</h3></center>
   In the NewOS shell script language it is possible to write formulas the 
   same way as in most   modern  programming languages.<br> 
   The shell can handle the following operators:<br>
        +, -, /, *, =, &lt;=, =, =&gt;, &lt;, &gt;, !=, ==<br>
   <br>
   All operators can be used with numerical values, and are calculated
   as integers.<br>
   String values can only be used with the compare operators(=,&lt;=,=&gt; etc..)
   and the load operator(=).<br>
   The compare operator returns a value 1 or 0 for true of false<br>
   It is not possible to mix strings and numbers in formulas, the program fails with 
   an error messages. But a string can be <a href="cast">cast</a> into a number 
   or vice versa<br>
   This is neccesary because some operator handle strings different as numbers :<br>
   <ul>
    <li>10&gt;2 is true</li>
    <li>"10"&gt;"2" is false</li>
   </ul>
  </td>
 </tr>
</table>

<hr>

<table border="0" width="100%" bgcolor="#E8E8E8">
 <tr>
  <td width="100%" height="100%" valign="top" align="left">
   <a name="Functions"></a>
   <center><h3>Functions</h3></center>
   <a name="exec_function"></a>
   <b>exec</b><br>
   <br>
   <u>syntax:</u><br>
   <br>
   <b>exec(</b>&lt;string expression&gt;)<br>
   <br>
   <u>description:</u><br>
   <br>
   The exec function starts program in &lt;string expression&gt; (which is
   the program name and parameters), waits until the process terminates and returns 
   the exit value.  When filename is not found the execution of the script terminates
   with an error  message.<br>
   This 'exec' function is using the &nbsp;path in $path as search path.<br>
   <br>
   <u>examples:</u><br>
   $program="shell $p0"<br>
   $result=exec($program)<br>
   <br>
   or<br>
   <br>
   $result=exec("shell /boot/bin/initX")<br>
   <br>

   <a name="casting"></a>
   <b>type casting: number() and string()</b><br>
   <br>
   <u>syntax</u><br>
   &nbsp;&nbsp;&nbsp; number(&lt;expression&gt;)<br>
   &nbsp;&nbsp;&nbsp; string(&lt;expression&gt;)<br>
   <br>
   The shell makes a distinction between strings &nbsp;and number. '1' is a 
   string all though it contains a number.<br>
   <b>number('1')</b> casts the string into a number. <br>
   <br>
   <b>string </b>converts a number to a string.<br>
   <br>
   <u>examples</u><br>
   <br>
   $a=2<br>
   if($p1==$a+1) goto somewhere<br>
   <br>
   Fails because &nbsp;parameters($p1) is always a string, this should be:<br>
   <br>
   $a=2<br>
   if($p1==string($a+1)) goto somewhere<br>
   <br>
   or<br>
   <br>
   $a=2<br>
   if(number($p1)==$a+1) goto somewhere<br>
   <br>
   The difference between the last 2 examples is that the 'number' cast fails 
   when $p1 doesn't contain a valid number.
  </td>
 </tr>
</table>

<hr>

<table border="0" width="100%" bgcolor="#E8E8E8">
 <tr>
  <td width="100%" height="100%" valign="top" align="left">
   <a name="Statements"></a>
   <center><h3>Statements</h3></center>
   <a name="Comments"></a>
   <b>Comments</b><br>
   Comments always start with the '#' character end at the line end.<br>
   <br>

   <a name="exec"></a>
   <b>exec</b><br>
   <u>Syntax:</u><br>
   &nbsp; &nbsp; &nbsp;[<b>exec</b>] &lt;program_name&gt; &lt;options&gt;<br>
   <br>
   <u>description:</u><br>
   This command starts another process and executes a binary program.<br>
   A program can also started by just using the &lt;program_name&gt;. The exec 
   statement is optional but when the &lt;program_name&gt; is a detemened by 
   a variable the 'exec' statements must be used.<br>
   <br>
   The exec statement can have the following 'options':<br>
   <ul>
    <li>'&amp;' at the end: The shell doesn't wait until the process ends</li>
    <li>Output redirection</li>
   </ul>
   <u>Examples</u><br>
   $texteditor = "word"<br>
   if($no_ms) $texteditor="vi"<br>
   exec $texteditor $p1<br>
   <br>
   <a name="exit"></a>
   <b>exit</b><br>
   <u>Syntax:</u><br
   &nbsp; &nbsp; &nbsp;<b>exit</b> [(&lt;expression&gt;)]<br>
   <br>
   <u>description:</u><br>
   The program exits with exit value &lt;expression&gt;.<br>
   <br>
   When script is started without the -s option the shell always exits 
   after the script ends.<br>
   When no expression is given, the exit code is 0.<br>
   Expression must be a number.<br>
   <br>

   <a name="goto"></a>
   <b>goto</b><br>
   <u>Syntax:</u><br>
   &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;<b>goto</b> &lt;label_name&gt;<br>
   <br>
   <u>description:</u><br>
   After the 'goto' statement the program execution starts after the label 
   &lt;label_name&gt;.<br>
   When label can't be found, the program fails with 'label not found' error.<br>
   <br>

   <a name="if"></a>
   <b>if</b><br>
   <u>Syntax:</u><br>
   &nbsp; &nbsp; &nbsp; &nbsp; <b>if</b>(&lt;expression&gt;) &lt;statement&gt;<br>
   <br>
   <u>description:</u><br>
   &lt;statement&gt; is executed when &lt;expression&gt; &lt;&gt; 0<br>
   Only one statement can follow 'if'.<br>
   <br>

   <a name="labels"></a>
   <b>labels</b><br>
   <u>Syntax:</u><br>
   &nbsp; &nbsp; &nbsp; &lt;label_name&gt;:<br>
   <br>
   <u>Note:</u><br>
   The script file is not yet checked for duplicate labels.
  </td>
 </tr>
</table>

<hr>

<table border="1" width="100%" bgcolor="#D9D5FF">
 <tr> 
  <td width="100%" height="49" valign="top" align="center"><small><font color="#000000">This
   page copyright 2002 </font></small><font size="2">
<!--   <br>
   Any questions, comments, gripes, whatever: 
   <a href="mailto:geist@newos.org">geist@newos.org</a></font>
  -->
  </td>
 </tr>
</table>
   
</body>
</html>

